﻿namespace wwl.Contract.Dtos.Common
{
  /// <summary>
  /// 分页查询结果的泛型封装类，用于统一返回分页数据及分页元信息
  /// </summary>
  /// <typeparam name="T">分页数据中每条记录的实体类型</typeparam>
  public class PagedResult<T>
  {
    /// <summary>
    /// 当前页的数据集合
    /// </summary>
    /// <remarks>
    /// 包含当前页的实际数据，数量最多不超过<see cref="PageSize"/>（最后一页可能少于该值）
    /// 初始化时默认创建空集合，避免空引用异常
    /// </remarks>
    public List<T> Items { get; set; } = new();

    /// <summary>
    /// 符合查询条件的总记录数
    /// </summary>
    /// <remarks>用于计算总页数和判断分页边界（如是否有下一页）</remarks>
    public int TotalCount { get; set; }

    /// <summary>
    /// 当前页码（从1开始）
    /// </summary>
    /// <remarks>与请求参数中的<see cref="PagedRequest.PageIndex"/>对应</remarks>
    public int PageIndex { get; set; }

    /// <summary>
    /// 每页显示的记录数
    /// </summary>
    /// <remarks>与请求参数中的<see cref="PagedRequest.PageSize"/>对应，决定单页数据量上限</remarks>
    public int PageSize { get; set; }

    /// <summary>
    /// 总页数
    /// </summary>
    /// <remarks>
    /// 通过总记录数和每页大小计算得出，向上取整（如101条记录，每页20条，总页数为6）
    /// 计算公式：TotalPages = 天花板(TotalCount / PageSize)
    /// </remarks>
    public int TotalPages => (int)Math.Ceiling(TotalCount / (double)PageSize);

    /// <summary>
    /// 是否有上一页
    /// </summary>
    /// <remarks>当前页码大于1时返回true，用于前端判断是否显示"上一页"按钮</remarks>
    public bool HasPrevious => PageIndex > 1;

    /// <summary>
    /// 是否有下一页
    /// </summary>
    /// <remarks>当前页码小于总页数时返回true，用于前端判断是否显示"下一页"按钮</remarks>
    public bool HasNext => PageIndex < TotalPages;
  }
}
